class Face

Parent: Drawingelement

Class Index

Methods:all_connected, area, back_material, back_material=, edges, followme, get_UVHelper, loops, mesh, normal, outer_loop, plane, position_material, pushpull, reverse!, vertices

Sample Code:facetests.rb

Instance Methods

all_connected

The all_connected method retrieves all of the entities connected to a face.

Syntax:

entities = face.all_connected

Arguments:

Return Value:

entities - the entities connected to the face

Comments:

Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
entity1 = entities[0]
entities = entity1.all_connected
if (entities)
UI.messagebox entities
else
UI.messagebox "Failure"
end       

area

The area method is used to retrieve the area of a face in current units.

Syntax:

area = face.area

Arguments:

Return Value:

area - the area of the face in current units (if successful)

Comments:

Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
area = face.area

back_material

The back_material method is used to retrieve the material assigned to the back side of the face.

Syntax:

material = face.back_material

Arguments:

Return Value:

material - a Material object representing the material on the back of the face (if successful)

Comments:

Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
area = face.area
back = face.back_material

back_material=

The back_material= method is used to set the material assigned to the back side of the face.

Syntax:

material = face.back_material = "material_name" | material

Arguments:

"material_name" - the name of a valid material

material - a Material object

Return Value:

material - the name of the valid material or the new Material object (if successful)

Comments:

Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = face.back_material="red"

edges

The edges method is used to get an array of edges that bound the face.

Syntax:

edges = face.edges

Arguments:

Return Value:

edges - an array of Edge objects (if successful)

Comments:

Example:

depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
edges = face.edges

followme

The followme method is used creating a shape by making the face follow along an array of edges.

Syntax:

status = face.followme edge1, edge2, ...

status = face.followme [edge1, edge2, ...]

Arguments:

edge1 - an Edge object to follow

Return Value:

status - true if successful, nil if unsuccessful

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
line = entities.add_line point1, point2
begin
status = face.followme line
rescue
UI.messagebox $!.message
end

get_UVHelper

The get_UVHelper object is used to retrieve a UVHelper object for use in texture manipulation on a face.

Syntax:

uvhelper = face.get_UVHelper front, back, texturewriter

Arguments:

front - true if you want the texture coordinates for the front face, false if not

back - true if you want the texture coordinates for the back face, false if not

texturewriter - a TextureWriter object

Return Value:

uvhelper - a UVHelper object

Comments:

Example:

uvHelp = face.get_UVHelper true, true, tw

loops

The loops method is used to get an array of all of the loops that bound the face.

Syntax:

loops = face.loops

Arguments:

Return Value:

loops - an array of Loop objects if successful

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
loops = face.loops

mesh

The mesh method creates a polygon mesh that represents the face. See the PolygonMesh class for more information.

Syntax:

mesh = face.mesh flags

Arguments:

flags - one or more flags used to generate a polygon mesh (see comments)

Return Value:

mesh - a PolygonMesh object if successful

Comments:

Valid flags are:

0 (Include PolygonMeshPoints)
1 (Include PolygonMeshUVQFront)
2 (Include PolygonMeshUVQBack)
4 (Include PolygonMeshNormals).

Add these numbers together to combine flags. A value of 5 will include all flags, for example.

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
mesh = face.mesh 7

normal

The normal method is used to retrieve the 3d vector normal to the face in the front direction.

Syntax:

vector = face.normal

Arguments:

Return Value:

vector - a Vector3d object if successful

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
normal = face.normal

outer_loop

This method is used to retrieve the outer loop that bounds the face.

Syntax:

loop = face.outer_loop

Arguments:

Return Value:

loop - a Loop object representing the outer loop (if successful)

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
loop = face.outer_loop

plane

The plane method is used to retrieve the plane of the face.

Syntax:

plane = face.plane

Arguments:

Return Value:

plane - a plane that contains the face (if successful)

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
plane = face.plane

position_material

The position_material method is used to position a material on a face.

Syntax:

face.position_material material, pt_array, on_front

Arguments:

material -  a Material object

pt_array - an array of Point3d objects used to position the material

o_front - true to position the texture on the front of the Face or false to position it on the back of the Face.

Return Value:

Comments:

The pt_array must contain 2, 4, 6 or 8 points. The points are used in pairs to tell where a point in the texture image is positioned on the Face. The first point in each pair is a 3D point in the model. It should be a point on the Face. The second point in each pair of points is a 2D point that gives the (u,v) coordinates of a point in the image to match up with the 3D point.

Example:

pushpull

The pushpull method is used to perform a push/pull on a face.

Syntax:

face.pushpull distance

Arguments:

distance - the distance, in current units, to push/pull the face

Return Value:

Comments:

The distance is measured in the direction that the face normal is pointing.

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = face.pushpull 100

reverse!

The reverse! method is used to reverse the face's orientation.

Syntax:

face = face.reverse!

Arguments:

Return Value:

face- the reversed Face object if successful, false if unsuccessful

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
status = face.reverse!

vertices

The vertices method is used to retrieve an array of vertexes used by the edges of the face.

Syntax:

vertices = face.vertices

Arguments:

Return Value:

vertices - an array of Vertex objects

Comments:

Example:

point1 = Geom::Point3d.new (0,0,0)
point2 = Geom::Point3d.new (0,0,100)
depth = 100
width = 100
model = Sketchup.active_model
entities = model.active_entities
pts = []
pts[0] = [0, 0, 0]
pts[1] = [width, 0, 0]
pts[2] = [width, depth, 0]
pts[3] = [0, depth, 0]
# Add the face to the entities in the model
face = entities.add_face pts
vertices = face.vertices